///////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2009 Summit Contributors.  
// See: http://code.google.com/p/tyemill/wiki/SummitContributors
//
// The name and logo of Summit are trademarks of TYEMILL, LLC - All Rights 
// Reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a 
// copy of this software and associated documentation files (the "Software"), 
// to deal in the Software without restriction, including without 
// limitation the rights to use, copy, modify, merge, publish, distribute, 
// sublicense, and/or sell copies of the Software, and to permit persons to 
// whom the Software is furnished to do so, subject to the following 
// conditions:
//
// The above copyright notice and this permission notice shall be included 
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
// DEALINGS IN THE SOFTWARE.
///////////////////////////////////////////////////////////////////////////////

package summit.basecamp.helpers
{
import flash.net.URLRequestMethod;

import summit.basecamp.constants.BasecampOperation;
import summit.basecamp.constants.BasecampResource;
import summit.basecamp.constants.TodoListFilter;
import summit.net.BasecampRequest;
import org.tyemill.utils.Assert;
	
/**
 * Helpers for Basecamp todo-list operations.
 */
public class TodoListHelper
{	
	/** @private storage **/
	private static const TYPE:String = BasecampResource.TODOLIST;
	private static const PATH_HELPER:String = "/todo_lists/";
	private static const ALL:String = TodoListFilter.ALL;
	
	/** @private **/
	public function TodoListHelper()
	{
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for creating a todo-list.
	 * 
	 * <p>Typically, the XML provided is based on the template returned from
	 * a call to <code>prepare</code>.
	 * 
	 * <p>The <code>project-id</code>, which represents the project associated
	 * with the todo-list, is required.</p>
	 * 
	 * <p>Note: The new todo-list is always placed below all other existing 
	 * todo-lists (visually).</p>
	 * 
	 * @param content Represents a todo-list to be created.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function create(content:XML):BasecampRequest
	{
		// POST /projects/#{project_id}/todo_lists.xml
		// Returns HTTP status code 201 ("Created")
		
		var projectId:String = content.child("project-id")[0];
		
		SharedOperations.nullEmptyAssert(projectId, 
		"content did not contain a valid project-id", true);
		
		return new BasecampRequest(
		"/projects/" + projectId + "/todo_lists.xml", URLRequestMethod.POST,
		TYPE, BasecampOperation.CREATE, content);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for deleting a todo-list.
	 * 
	 * @param id The id of the todo-list to be deleted.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */ 
	public static function destroy(id:String):BasecampRequest
	{
		return SharedOperations.destroy(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for getting an existing todo-list
	 * from the store.
	 * 
	 * <p>The XML returned is pre-filled with the existing values of 
	 * the identified todo-list, and is ready to be resubmitted via the 
	 * <code>update</code> function.</p>
	 * 
	 * @param id The id of the todo-list to be retrieved.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */ 
	public static function edit(id:String):BasecampRequest
	{
		return SharedOperations.edit(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a list of todo-lists.
	 * 
	 * <p>If a <code>projectId</code> is given, the list of lists is scoped 
	 * to the specified project. In this case, <code>filter</code> can be used
	 * to further scope the lists.</p>
	 * 
	 * <p>If <code>projectId</code> is not provided, the query will span
	 * across all lists for all projects. If no <code>responsibleParty</code>
	 * is provided, the query will yield todo-lists with todo-items assigned
	 * to the requesting user.</p>
	 * 
	 * @param projectId The id of the project from which todo-lists are 
	 * queried.
	 * @param filter Defines the query that determines which todo-lists to
	 * return. Possible values include:
	 * <ul>
	 *		<li><code>TodoListFilter.ALL</code>, the default, gets all 
	 * 		todo-lists for the project todo-items.</li>
	 *		
	 *		<li><code>TodoListFilter.PENDING</code> gets all todo-lists that 
	 * 		have todo-items that are NOT complete.</li>
	 * 
	 * 		<li><code>TodoListFilter.FINISHED</code> gets all todo-lists that 
	 * 		ONLY contain todo-items that are complete.</li>
	 * </ul>
	 * @param responsibleParty The id of the user or the company from which 
	 * to todo-lists are queried. If no responsibleParty is provided (null), 
	 * todo-lists are returned for all users. If responsibleParty is provided 
	 * as an empty string (""), only unassigned items are returned. 
	 * If the responsibleParty is a company, the company id provided should be 
	 * preceeded with a "c", such as "c1234".
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 * 
	 * @see 
	 * summit.basecamp.constants.TodoListFilter
	 */
	public static function list(projectId:String, 
	filter:String = "all", responsibleParty:String = null):BasecampRequest
	{
		if(projectId)
		{
			// GET /projects/#{project_id}/todo_lists.xml?filter=#{filter}
			return new BasecampRequest(
			"/projects/" + projectId + "/todo_lists.xml?filter=" + filter,
			URLRequestMethod.GET, TYPE, BasecampOperation.LIST);
		}
		else
		{
			responsibleParty = (null == responsibleParty ? null : 
							"?responsibleParty=" + responsibleParty);
							
			var stdCall:String = "/todo_lists.xml";
	
			return new BasecampRequest(
			null == responsibleParty ? stdCall : stdCall + responsibleParty,
			URLRequestMethod.GET, TYPE, BasecampOperation.LIST);
		}
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a single todo-list.
	 * 
	 * @param id The id of the todo-list to be read.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function read(id:String):BasecampRequest
	{
		return SharedOperations.read(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reordering todo-lists.
	 * 
	 * <p>Lists that only contain completed todo-items (eg completed lists) 
	 * can not be reordered.</p>
	 * 
	 * <p>Lists that are not referenced in <code>content</code> are reordered
	 * below the referenced todo-lists.</p>
	 * 
	 * @param content The list of todo-lists to be reordered.
	 * @param projectId The id of the project that are associated with the 
	 * todo-lists.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function reorder(content:XML, 
	projectId:String):BasecampRequest
	{
		SharedOperations.nullEmptyAssert(projectId, "projectId");
		
		// POST /projects/#{project_id}/todo_lists/reorder.xml
		// Returns HTTP status code 200 on success.
		
		return new BasecampRequest("/projects/" + projectId + 
		"/todo_lists/reorder.xml", URLRequestMethod.POST, TYPE,
		BasecampOperation.REORDER, content);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for retrieving a template for a 
	 * new todo-list.
	 * 
	 * <p>The template retrieved is used with <code>create</code> to 
	 * submit a new todo-list.</p>
	 * 
	 * @param projectId The id of the project that is to be associated with 
	 * the todo-list when submitted via a call to <code>create</code>.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */ 
	public static function prepare(projectId:String):BasecampRequest
	{	
		SharedOperations.nullEmptyAssert(projectId, "projectId");
		
		return SharedOperations.prepare("/projects/" + projectId + 
			PATH_HELPER + "new.xml", "project-id", projectId, 
			TYPE); 
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for updating an existing 
	 * todo-list.
	 * 
	 * <p><code>content</code> submitted to <code>update</code> is typically
	 * retrieved from <code>edit</code>.</p>
	 * 
	 * @param content The updated XML content of an existing todo-list.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>. 
	 */ 
	public static function update(content:XML):BasecampRequest
	{
		return SharedOperations.update(content, PATH_HELPER, TYPE);
	}
}
}
//////////////////////////////////////////////////////// gmarius@tyemill.com //